home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 52 / Amiga Format AFCD52 (Issue 136, May 2000).iso / -serious- / programming / c / icu-1.3.1 / icu-bin / include / ustdio.h < prev    next >
C/C++ Source or Header  |  2000-02-23  |  12KB  |  360 lines
  1. /*
  2. *******************************************************************************
  3. *                                                                             *
  4. * COPYRIGHT:                                                                  *
  5. *   (C) Copyright International Business Machines Corporation, 1999           *
  6. *   Licensed Material - Program-Property of IBM - All Rights Reserved.        *
  7. *   US Government Users Restricted Rights - Use, duplication, or disclosure   *
  8. *   restricted by GSA ADP Schedule Contract with IBM Corp.                    *
  9. *                                                                             *
  10. *******************************************************************************
  11. *
  12. * File ustdio.h
  13. *
  14. * Modification History:
  15. *
  16. *   Date        Name        Description
  17. *   10/16/98    stephen     Creation.
  18. *   11/06/98    stephen     Modified per code review.
  19. *   03/12/99    stephen     Modified for new C API.
  20. *   07/19/99    stephen     Minor doc update.
  21. *******************************************************************************
  22. */
  23.  
  24. #ifndef USTDIO_H
  25. #define USTDIO_H
  26.  
  27. #include <stdio.h>
  28. #include <stdarg.h>
  29.  
  30. #include "utypes.h"
  31. #include <ucnv.h>
  32.  
  33.  
  34. /** Forward declaration of a Unicode-aware file */
  35. typedef struct UFILE UFILE;
  36.  
  37.  
  38.  
  39. /**
  40.  * Open a UFILE.
  41.  * A UFILE is a wrapper around a FILE* that is locale and codepage aware.
  42.  * That is, data written to a UFILE will be formatted using the conventions
  43.  * specified by that UFILE's Locale; this data will be in the character set
  44.  * specified by that UFILE's codepage.
  45.  * @param filename The name of the file to open.
  46.  * @param perm The read/write permission for the UFILE; one of "r", "w", "rw"
  47.  * @param locale The locale whose conventions will be used to format 
  48.  * and parse output. If this parameter is NULL, the default locale will 
  49.  * be used.
  50.  * @param codepage The codepage in which data will be written to and
  51.  * read from the file. If this paramter is NULL, data will be written and
  52.  * read using the default codepage for <TT>locale</TT>, unless <TT>locale</TT>
  53.  * is NULL, in which case the system default codepage will be used.
  54.  * @return A new UFILE, or 0 if an error occurred.
  55.  */
  56. U_CAPI UFILE*
  57. u_fopen(const char    *filename,
  58.     const char    *perm,
  59.     const char    *locale,
  60.     const char    *codepage);
  61.  
  62. /**
  63.  * Open a UFILE on top of an existing FILE* stream.
  64.  * @param f The FILE* to which this UFILE will attach.
  65.  * @param locale The locale whose conventions will be used to format 
  66.  * and parse output. If this parameter is NULL, the default locale will 
  67.  * be used.
  68.  * @param codepage The codepage in which data will be written to and
  69.  * read from the file. If this paramter is NULL, data will be written and
  70.  * read using the default codepage for <TT>locale</TT>, unless <TT>locale</TT>
  71.  * is NULL, in which case the system default codepage will be used.
  72.  * @return A new UFILE, or 0 if an error occurred.
  73.  */
  74. U_CAPI UFILE*
  75. u_finit(FILE        *f,
  76.     const char    *locale,
  77.     const char    *codepage);
  78.  
  79. /**
  80.  * Close a UFILE.
  81.  * @param file The UFILE to close.
  82.  */
  83. U_CAPI void
  84. u_fclose(UFILE *file);
  85.  
  86. /**
  87.  * Get the FILE* associated with a UFILE.
  88.  * @param f The UFILE
  89.  * @return A FILE*, owned by the UFILE.  The FILE <EM>must not</EM> be closed.
  90.  */
  91. U_CAPI FILE*
  92. u_fgetfile(UFILE *f);
  93.  
  94. /**
  95.  * Get the locale whose conventions are used to format and parse output.
  96.  * This is the same locale passed in the preceding call to<TT>u_fsetlocale</TT>
  97.  * or <TT>u_fopen</TT>.
  98.  * @param file The UFILE to set.
  99.  * @return The locale whose conventions are used to format and parse output.
  100.  */
  101. U_CAPI const char*
  102. u_fgetlocale(UFILE *file);
  103.  
  104. /**
  105.  * Set the locale whose conventions will be used to format and parse output.
  106.  * @param locale The locale whose conventions will be used to format 
  107.  * and parse output.
  108.  * @param file The UFILE to query.
  109.  * @return 0 if successful, otherwise a negative number.
  110.  */
  111. U_CAPI int32_t
  112. u_fsetlocale(const char        *locale,
  113.          UFILE        *file);
  114.  
  115. /**
  116.  * Get the codepage in which data is written to and read from the UFILE.
  117.  * This is the same codepage passed in the preceding call to 
  118.  * <TT>u_fsetcodepage</TT> or <TT>u_fopen</TT>.
  119.  * @param file The UFILE to query.
  120.  * @return The codepage in which data is written to and read from the UFILE,
  121.  * or 0 if an error occurred.
  122.  */
  123. U_CAPI const char*
  124. u_fgetcodepage(UFILE *file);
  125.  
  126. /**
  127.  * Set the codepage in which data will be written to and read from the UFILE.
  128.  * All Unicode data written to the UFILE will be converted to this codepage
  129.  * before it is written to the underlying FILE*.
  130.  * @param codepage The codepage in which data will be written to 
  131.  * and read from the file. For example <TT>"latin-1"</TT> or <TT>"ibm-943</TT>.
  132.  * A value of NULL means the default codepage for the UFILE's current 
  133.  * locale will be used.
  134.  * @param file The UFILE to set.
  135.  * @return 0 if successful, otherwise a negative number.
  136.  */
  137. U_CAPI int32_t
  138. u_fsetcodepage(const char    *codepage,
  139.            UFILE        *file);
  140.  
  141.  
  142. /**
  143.  * Returns an alias to the converter being used for this file.
  144.  * @param file The UFILE to set.
  145.  * @return alias to the converter
  146.  */
  147. U_CAPI UConverter *u_fgetConverter(UFILE *f);
  148.  
  149. /* Output functions */
  150.  
  151. /**
  152.  * Write formatted data to a UFILE.
  153.  * @param f The UFILE to which to write.
  154.  * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will
  155.  * interpret the variable arguments received and format the data.
  156.  * @return The number of Unicode characters written to <TT>f</TT>.
  157.  */
  158. U_CAPI int32_t 
  159. u_fprintf(    UFILE        *f,
  160.         const char    *patternSpecification,
  161.         ... );
  162.  
  163. /**
  164.  * Write formatted data to a UFILE.
  165.  * This is identical to <TT>u_fprintf</TT>, except that it will
  166.  * <EM>not</EM> call <TT>va_start/TT> and <TT>va_end</TT>.
  167.  * @param f The UFILE to which to write.
  168.  * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will
  169.  * interpret the variable arguments received and format the data.
  170.  * @param ap The argument list to use.
  171.  * @return The number of Unicode characters written to <TT>f</TT>.
  172.  * @see u_fprintf
  173.  */
  174. U_CAPI int32_t 
  175. u_vfprintf(    UFILE        *f,
  176.         const char    *patternSpecification,
  177.         va_list        ap);
  178.  
  179. /**
  180.  * Write formatted data to a UFILE.
  181.  * @param f The UFILE to which to write.
  182.  * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will
  183.  * interpret the variable arguments received and format the data.
  184.  * @return The number of Unicode characters written to <TT>f</TT>.
  185.  */
  186. U_CAPI int32_t 
  187. u_fprintf_u(    UFILE        *f,
  188.         const UChar    *patternSpecification,
  189.         ... );
  190.  
  191. /**
  192.  * Write formatted data to a UFILE.
  193.  * This is identical to <TT>u_fprintf_u</TT>, except that it will
  194.  * <EM>not</EM> call <TT>va_start/TT> and <TT>va_end</TT>.
  195.  * @param f The UFILE to which to write.
  196.  * @param patternSpecification A pattern specifying how <TT>u_fprintf</TT> will
  197.  * interpret the variable arguments received and format the data.
  198.  * @param ap The argument list to use.
  199.  * @return The number of Unicode characters written to <TT>f</TT>.
  200.  * @see u_fprintf_u
  201.  */
  202. U_CAPI int32_t 
  203. u_vfprintf_u(    UFILE        *f,
  204.         const UChar    *patternSpecification,
  205.         va_list        ap);
  206.  
  207. /**
  208.  * Write a Unicode to a UFILE.  The null (U+0000) terminated UChar*
  209.  * <TT>s</TT> will be written to <TT>f</TT>, excluding the NULL terminator.
  210.  * A newline will be added to <TT>f</TT>.
  211.  * @param s The UChar* to write.
  212.  * @param f The UFILE to which to write.
  213.  * @return A non-negative number if successful, EOF otherwise.
  214.  */
  215. U_CAPI int32_t
  216. u_fputs(const UChar    *s,
  217.     UFILE        *f);
  218.  
  219. /**
  220.  * Write a UChar to a UFILE.
  221.  * @param uc The UChar to write.
  222.  * @param f The UFILE to which to write.
  223.  * @return The character written if successful, EOF otherwise.
  224.  */
  225. U_CAPI int32_t
  226. u_fputc(UChar        uc,
  227.     UFILE        *f);
  228.  
  229. /**
  230.  * Write Unicode to a UFILE.
  231.  * The ustring passed in will be converted to the UFILE's underlying
  232.  * codepage before it is written.
  233.  * @param chars A pointer to the Unicode data to write.
  234.  * @param count The number of Unicode characters to write
  235.  * @param f The UFILE to which to write.
  236.  * @return The number of Unicode characters written.
  237.  */
  238. U_CAPI int32_t
  239. u_file_write(const UChar     *chars, 
  240.          int32_t        count, 
  241.          UFILE         *f);
  242.  
  243.  
  244. /* Input functions */
  245.  
  246. /**
  247.  * Read formatted data from a UFILE.
  248.  * @param f The UFILE from which to read.
  249.  * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will
  250.  * interpret the variable arguments received and parse the data.
  251.  * @return The number of items successfully converted and assigned, or EOF
  252.  * if an error occurred.
  253.  */
  254. U_CAPI int32_t 
  255. u_fscanf(    UFILE        *f,
  256.         const char     *patternSpecification,
  257.         ... );
  258.  
  259. /**
  260.  * Read formatted data from a UFILE.
  261.  * This is identical to <TT>u_fscanf</TT>, except that it will
  262.  * <EM>not</EM> call <TT>va_start/TT> and <TT>va_end</TT>.
  263.  * @param f The UFILE from which to read.
  264.  * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will
  265.  * interpret the variable arguments received and parse the data.
  266.  * @param ap The argument list to use.
  267.  * @return The number of items successfully converted and assigned, or EOF
  268.  * if an error occurred.
  269.  * @see u_fscanf
  270.  */
  271. U_CAPI int32_t 
  272. u_vfscanf(    UFILE        *f,
  273.         const char     *patternSpecification,
  274.         va_list        ap);
  275.  
  276. /**
  277.  * Read formatted data from a UFILE.
  278.  * @param f The UFILE from which to read.
  279.  * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will
  280.  * interpret the variable arguments received and parse the data.
  281.  * @return The number of items successfully converted and assigned, or EOF
  282.  * if an error occurred.
  283.  */
  284. U_CAPI int32_t 
  285. u_fscanf_u(    UFILE        *f,
  286.         const UChar     *patternSpecification,
  287.         ... );
  288.  
  289. /**
  290.  * Read formatted data from a UFILE.
  291.  * This is identical to <TT>u_fscanf_u</TT>, except that it will
  292.  * <EM>not</EM> call <TT>va_start/TT> and <TT>va_end</TT>.
  293.  * @param f The UFILE from which to read.
  294.  * @param patternSpecification A pattern specifying how <TT>u_fscanf</TT> will
  295.  * interpret the variable arguments received and parse the data.
  296.  * @param ap The argument list to use.
  297.  * @return The number of items successfully converted and assigned, or EOF
  298.  * if an error occurred.
  299.  * @see u_fscanf_u
  300.  */
  301. U_CAPI int32_t 
  302. u_vfscanf_u(    UFILE        *f,
  303.         const UChar     *patternSpecification,
  304.         va_list        ap);
  305.  
  306. /**
  307.  * Read a UChar* from a UFILE.
  308.  * @param f The UFILE from which to read.
  309.  * @param n The maximum number of characters - 1 to read.
  310.  * @param s The UChar* to receive the read data.  Characters will be
  311.  * stored successively in <TT>s</TT> until a newline or EOF is
  312.  * reached. A NULL character (U+0000) will be appended to <TT>s</TT>.
  313.  * @return A pointer to <TT>s</TT>, or 0 if no characters were available.
  314.  */
  315. U_CAPI UChar*
  316. u_fgets(UFILE        *f,
  317.     int32_t        n,
  318.     UChar        *s);
  319.  
  320. /**
  321.  * Read a UChar from a UFILE.
  322.  * @param f The UFILE from which to read.
  323.  * @return The UChar value read, or U+FFFF if no character was available.
  324.  */
  325. U_CAPI UChar
  326. u_fgetc(UFILE        *f);
  327.  
  328. /**
  329.  * Unget a UChar from a UFILE.
  330.  * If this function is not the first to operate on <TT>f</TT> after a call
  331.  * to <TT>u_fgetc</TT>, the results are undefined.
  332.  * @param c The UChar to put back on the stream.
  333.  * @param f The UFILE to receive <TT>c</TT>.
  334.  * @return The UChar value put back if successful, U+FFFF otherwise.
  335.  */
  336. U_CAPI UChar
  337. u_fungetc(UChar        c,
  338.       UFILE        *f);
  339.  
  340. /**
  341.  * Read Unicode from a UFILE.
  342.  * Bytes will be converted from the UFILE's underlying codepage, with
  343.  * subsequent conversion to Unicode.
  344.  * @param chars A pointer to receive the Unicode data.
  345.  * @param count The number of Unicode characters to read.
  346.  * @param f The UFILE from which to read.
  347.  * @return The number of Unicode characters read.
  348.  */
  349. U_CAPI int32_t
  350. u_file_read(UChar        *chars, 
  351.         int32_t        count, 
  352.         UFILE         *f);
  353.  
  354. #endif
  355.  
  356.  
  357.  
  358.  
  359.  
  360.